Skip to content

Document the committed program and its fixed operands in the README - #10

Merged
dmccoystephenson merged 2 commits into
masterfrom
feature/readme-document-committed-program
Sep 4, 2026
Merged

Document the committed program and its fixed operands in the README#10
dmccoystephenson merged 2 commits into
masterfrom
feature/readme-document-committed-program

Conversation

@dmccoystephenson

@dmccoystephenson dmccoystephenson commented Sep 2, 2026

Copy link
Copy Markdown
Member

Summary

This cycle was devoted to a documentation-accuracy sweep, since every open issue is blocked on either an owner design decision or an LC-3 toolchain that is not installed in this environment.

  • README.md gains a What is committed section describing the two blocks that are actually in src/multiplyTwoNumbers.asm: TESTCODE: (clears R1 and R2, then loads 5 and 6) and MULTIPLY: (clears R0, then adds R1 into R0 and decrements R2 each pass, branching back to AGAIN).
  • The drift between the README's opening sentence and the committed source is disclosed rather than resolved. That the operands are fixed at 5 and 6 by TESTCODE: is now stated plainly, alongside the header comment's caller-supplied contract, and the note records that which of the two is intended has not been decided. Deciding it is reserved for the repository owner and is tracked in TESTCODE: overwrites the caller-supplied operands the header comment and README document #2 — nothing in this diff picks a side.
  • A short Building and running section records that no LC-3 assembler or simulator is named by this repository yet. Naming one that was never run was deliberately avoided.
  • src/multiplyTwoNumbers.asm is not touched. No toolchain is named, no command is claimed to have been run, and no register value is asserted anywhere in the diff.

No Closes #N reference is included. Issue #5 is partially advanced — the hardcoded operands it asks to have disclosed are now disclosed — but the build and run commands it asks for cannot be written honestly here, so it is left open.

Test plan

UNVERIFIED — not applicable. No LC-3 assembler or simulator exists in this environment (which lc3as lc3sim lc3convert complx lc3tools lc3 exits 1 with no output), so the syntax and behavior gates could not be run. Per this loop's scope gate that is acceptable for this PR specifically, because the diff touches only README.md, contains no commands, and asserts no register values.

  • git diff --stat reports README.md | 13 +++++++++++++, 1 file changed, 13 insertions(+) — the two pre-existing README lines are untouched and src/multiplyTwoNumbers.asm is not in the diff, so no CRLF renormalization was possible.
  • git diff --check reports nothing.
  • git status --porcelain shows no assembler artifact, no simulator script, and no .claude/ entry staged.
  • Every statement added to the README was checked against the source by line number: .ORIG x3000 (line 5), TESTCODE: (line 7), MULTIPLY: (line 13), AGAIN (line 15), BRp AGAIN (line 17), HALT (line 19).
  • Assemble and simulate — not run, no toolchain.

Issues deferred this cycle, with reasons

Issue #1 was closed during triage, having been resolved by the merged PR #9 but left open.

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

drafted by Claude on behalf of Daniel Stephenson

dmccoystephenson and others added 2 commits September 2, 2026 01:02
@dmccoystephenson @claude
Document the committed program and its fixed operands in the README
6892b5c 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@dmccoystephenson @claude
Describe the loop by its source order rather than by unverified behavior
5be87f4 
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@dmccoystephenson

dmccoystephenson commented Sep 2, 2026

Copy link
Copy Markdown
Member Author

Self-review

Posted as a plain comment rather than as a review object; independent review is not implied.

Rubric

  • Scope: PASS — git diff --name-only origin/master...HEAD lists README.md alone. No formatting churn, no rename, no .asm change.
  • Tests-new: PASS (vacuous) — no behavioral change is made, so no assemble-and-run command is owed. Every added statement is a positional fact about the source, each checked against a line number: .ORIG x3000 (5), TESTCODE: (7), MULTIPLY: (13), AGAIN (15), BRp AGAIN (17), HALT (19).
  • Tests-fix: not applicable — no bug is fixed by this diff.
  • Assembled, not read: PASS after two corrections. The first draft was scored FAIL on this item and amended in 5be87f4: while R2 remains positive was replaced, because it described a loop-trip property that only a simulator run could establish and it framed a body-before-test loop as a while-loop, which is exactly the behavior open issue Multiply loop tests after its body, so a zero or negative R2 is expected to yield a wrong product #6 disputes and this cycle cannot verify. The wording now records the source order only. the result is read out of R0 once the program halts was likewise attributed to the header comment rather than asserted as an observed outcome.
  • Register values are observed, not asserted: PASS — no register value appears anywhere in the diff. The numerals 5 and 6 are quoted from the ADD immediates on lines 10 and 11, not from a run.
  • CRLF preserved: PASS — src/multiplyTwoNumbers.asm is not in the diff at all, so no renormalization was possible. git diff --check reports nothing.
  • Contract coherence: PARTIAL, stated deliberately. The header comment, the README sentence, the GitHub repository description, and the code do not agree, and this PR does not make them agree — it discloses the disagreement and names it as undecided. Resolving it is reserved for the owner under TESTCODE: overwrites the caller-supplied operands the header comment and README document #2. The repository description is not a tracked file and was not edited.
  • Entry and exit intact: PASS — no source file is modified.
  • Operand legality / timeout on every run / toolchain probe present / no new toolchain: PASS (vacuous) — no immediate, no simulator invocation, no script, and no workflow is added by this diff.
  • No artifacts committed: PASS — git status --porcelain is clean; no .obj, .sym, .bin, .hex, simulator script, or .claude/ entry is present.
  • Issue resolution: PASS — no Closes #N is claimed. README documents nothing operational: no toolchain, no build or run command, no mention of the hardcoded operands #5 is advanced only in part and is deliberately left open.
  • Manual validation: UNVERIFIED, scope-gated. which lc3as lc3sim lc3convert complx lc3tools lc3 exits 1 with no output, so no assembler or simulator exists here. The gate is waived for this PR only because the diff is documentation containing no commands and no claimed register values. Any future PR touching src/multiplyTwoNumbers.asm must not take this waiver.

Findings folded in from the file, since both fall outside the current diff hunks

Summary: a documentation-only cycle that records what the committed file contains and discloses the fixed 5-and-6 operands, without resolving the contract question or naming a toolchain nobody ran. Merging is a human decision; behavior remains unverified in this environment, as it was for PR #9.

This comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

drafted by Claude on behalf of Daniel Stephenson

@dmccoystephenson dmccoystephenson mentioned this pull request Sep 2, 2026
Open
@dmccoystephenson
dmccoystephenson merged commit f85853a into master Sep 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@dmccoystephenson